Installing & Uninstalling

APIEngine v96 and later is the .NET 8 (ASP.NET Core) release line. On Windows it runs in IIS through the ASP.NET Core Module. On Linux it runs as a systemd service with Apache in front of it. Every 1.x version belongs to this line: after v96 the numbering changed from 8.96.x.y to 1.0.0, 1.0.1 and so on.

Coming from v95? v95 runs on .NET Framework 4.8 with a v4.0 application pool. v96+ needs a No Managed Code pool and the .NET 8 Hosting Bundle, so it is installed side by side and the bindings are moved across. See Upgrading from v95.

What you get

What you need

The installer checks these and lists anything missing with the command or download that fixes it. It never installs IIS, Apache, the Hosting Bundle or the .NET runtime itself; a run with a missing prerequisite stops with exit code 13 and changes nothing.

Installing

Download the package for your platform from the APIEngine area of the Innovative Releases portal:

1. Windows: apiengine.<version>.windows.zip
2. Linux: apiengine.<version>.linux.tar.gz

Extract it to a working folder that is outside the install folder.

Windows

1. Open PowerShell as Administrator.
2. Change to the extracted folder and run the installer:

1. If the server already has an APIEngine install, the installer lists it first and offers [0] Install a new APIEngine instance to add another one alongside it. Answer the prompts. Each has a default: name for this instance (default, which makes the site and pool APIEngine-default), install folder (<D: or C:>\Innovative\APIEngine-<instance>), host name (blank answers on every hostname; a pasted URL is reduced to its host name), HTTPS port (443), local HTTP port (8080, 0 for none; bound to 127.0.0.1) and the certificate to bind.
2. Pick an installed certificate from LocalMachine\My or LocalMachine\WebHosting, or accept the offer to create a self-signed certificate for the host. With no certificate the installer prints No https binding was created - there is no certificate to bind to one., creates no HTTPS binding and the site answers only on the local HTTP port. Choosing, binding and renewing a certificate: Certificates.
3. Open the Settings page from a browser on the server itself (https://localhost/, or http://127.0.0.1:8080/ when no HTTPS binding was created), enter the data server in Data Server Connection, and save.

The installer leaves the data server blank. The Settings page, section Data Server Connection, is where it is entered and changed afterwards.

The installer also generates the Token Secret, a random 41-character value, and writes it to App_Data\apiengine.settings. It is never shown or written to the installer log. Change it on the Settings page, section Security, to give every server in a farm the same value, or to invalidate every token issued so far.

The installer creates the application pool with No Managed Code, Integrated pipeline, Start Mode AlwaysRunning and Idle Time-out 0, creates the site, grants the pool Modify on the folders APIEngine writes to, starts the pool and checks that the running APIEngine reports the package version.

Linux

1. Change to the extracted folder and run the installer as root:

1. If the server already has an APIEngine install, the installer lists it first and offers Install a new APIEngine instance to add another one alongside it. Answer the prompts: unit name (apiengine), install folder (/opt/apiengine), Kestrel loopback port (5080) and the server name for the Apache vhost (a pasted URL is reduced to its host name).
2. The installer writes an Apache vhost (/etc/apache2/sites-available on Debian and Ubuntu, /etc/httpd/conf.d on Red Hat family systems) that uses the system's placeholder certificate. Replace it with the server's certificate as described on Certificates.
3. The installer writes App_Data/apiengine.settings with a generated Token Secret and a blank data server. Enter the data server on the Settings page, section Data Server Connection, from a browser on the server.

Installer options

Updating

Run the installer from the newer package. It lists the APIEngine installs it finds and upgrades the one you pick, showing the installed and package versions. Every upgrade asks Keep every current setting (quick install)? [Y/n]. Answer Y (the default) to upgrade with every current setting unchanged, or N to walk through the HTTPS port, host name, local HTTP port and certificate with the current values as defaults. -QuickInstall (Windows) or --quick-install (Linux) upgrades with no prompts at all.

On Windows an upgrade stops the application pool, renames the install folder to <install folder>.bak.<yyyyMMdd-HHmmss>, copies the new files into a fresh folder, restores App_Data (settings, procedure mappings) from the backup, re-grants permissions, starts the pool and verifies the version. A passed upgrade deletes the backup folder once the version check succeeds. A failed upgrade keeps it so the previous install can be recovered.

A local HTTP binding created before 1.0.19 answers on every address (*:8080). The upgrade reports it and leaves it as it is. New installs bind the local HTTP port to 127.0.0.1 only.

Uninstalling

Run the uninstaller from the extracted package folder. It lists the installs it finds and asks you to type the exact site (or unit) name to confirm: APIEngine-<instance> on Windows, apiengine-<instance> on Linux. The typed word must match exactly, including case.

After the typed confirmation, the uninstaller asks Remove the settings, logs and SMS media of '<instance>'? [Y/n]. Press Enter or answer Y (the default) to remove them with the install folder; answer N to keep them. A headless run (-Force or -Unattended, Linux --force or --unattended) removes them unless -KeepData (Linux --keep-data) is given. -RemoveData/-Purge (Linux --remove-data/--purge) are accepted for older command lines and have no effect - removing the data is already the default.

The uninstaller removes the IIS site and application pool (or the systemd unit and its Apache vhost), the install folder, and the self-signed certificate the installer created for the site. A File Server Path folder is removed only when it sits inside the install folder; one pointed outside the install folder is never touched. Any leftover upgrade backup (<install folder>.bak.<stamp>) is removed along with the rest of the data. IIS, Apache, the .NET runtime, other certificates, firewall rules, innovative-nats, innovative-postgresql and the SBN database are left in place. Copy App_Data\apiengine.settings somewhere safe first if you plan to reinstall.

Installer log

Every run writes install.log beside the install script, including runs that fail. Exit codes are listed on Troubleshooting.

First-start checks

On the server itself, http://127.0.0.1:8080 answers the same routes as HTTPS when the local HTTP binding exists. The local HTTP port listens on the loopback address only and is not reachable from other computers. If the browser cannot connect over HTTPS, the site may have no certificate bound; see Certificates and HTTPS binding with no certificate on Troubleshooting.

Manual setup (Windows)

For v96 builds that shipped without the installer, or to set up IIS by hand.

1. IIS, then the Hosting Bundle

Install IIS before the .NET 8 Hosting Bundle. The Hosting Bundle only registers the ASP.NET Core Module with IIS when IIS is already present; if IIS is added later, re-run the Hosting Bundle installer.

Download the .NET 8 Hosting Bundle from https://dotnet.microsoft.com/download/dotnet/8.0, run it, then run iisreset.

2. Confirm the ASP.NET Core Module

If any check fails, re-run the Hosting Bundle installer before going further; otherwise every request returns HTTP 500.19.

3. Application pool

4. Site

Create the site with the install folder as its physical path and the pool above. Add an HTTPS binding for each hostname with its certificate; several HTTPS hostnames on one IP address need Server Name Indication. Extract the package payload into the install folder and keep the web.config it ships with.

5. Folder permissions

Grant the pool Modify on each folder APIEngine writes to. Create a folder first if it does not exist. Replace APIEngine with the pool name, for example APIEngine-default.

When File Server Path or SMS Media Directory is set on the Settings page, grant Modify on that folder the same way.

6. Settings

Start the pool, open https://localhost/ from a browser on the server and complete the Settings page. A v95 apiengine.settings file cannot be copied across; enter the values again.

Upgrading from v95

Install v96+ beside v95 and move the bindings when it is proven. v95 stays untouched, so rolling back is moving the bindings back.

1. Install IIS and the .NET 8 Hosting Bundle if they are missing.
2. Run the installer (or the manual setup) with a new site name and a new install folder, for example APIEngine-v96 and D:\Innovative\APIEngine-v96, on a test hostname or a spare port.
3. Complete the Settings page for the new site.
4. Run the first-start checks and test every client against the new site.
5. Stop the v95 site, move its public HTTPS bindings to the new site and start the new site.
6. After a period of clean traffic, remove the v95 site, its pool and its folder.

Do not extract v96+ over a v95 folder. The two lines share file names but not hosting settings, and the mixed web.config that results fails with HTTP 500.19.